[release-1.7.3]: https://github.com/HuolalaTech/page-spy-web/releases/tag/v1.7.3
[public-data-event]: https://github.com/HuolalaTech/page-spy/blob/main/docs/plugin_zh.md#行為規約

import modalImg from '@/assets/image/screenshot/modal.png';
import replayImg from '@/assets/image/screenshot/replay-page.png';
import replayGif from '@/assets/image/screenshot/replay-page.gif';
import mpDataHarborImg from '@/assets/image/screenshot/mp-data-harbor.png';

## 概要#what

ログ再生は、オフラインデバッグ機能で、問題発生後に当時の実行データを確認・分析できます。履歴ログを再生することで、ビデオのように問題シーンを再現でき、リアルタイムでデバッグエンドに接続する必要はありません。

<a href={replayGif} target="_blank">
  <img src={replayGif} />
</a>

## なぜ必要か#why

PageSpyのオンラインデバッグ機能は強力ですが、クライアントとデバッグエンドが同時にオンラインである必要があります。これにはいくつかの制限があります：

- **人的コストが高い**：一つの問題に対して開発者とテスターが同時にオンラインで協力する必要がある
- **接続が不安定**：クライアントがバックグラウンドに移行したりネットワークが不安定だと接続が切断される
- **リアルタイム転送の負荷**：データ量とネットワーク転送のパフォーマンスを考慮する必要がある

これらの問題を解決するため、PageSpyは[1.7.3][release-1.7.3]バージョンでログ再生機能を提供し、デバッグをより柔軟にしました。

## 開始使用#start-using

### ブラウザでの使用#browser

PageSpyの完全な機能（オンラインデバッグとオフライン再生を含む）が必要な場合は、以下の手順で統合してください：

#### ステップ1：SDKとプラグインを導入#step-1

```html
<html>
  <head>
    <!-- 1. PageSpyを読み込む -->
    <script src="{deployUrl}/page-spy/index.min.js"></script>
    <!-- 2. DataHarborプラグインを読み込む：オフラインログデータをキャッシュし、アップロード/ダウンロード機能を提供 -->
    <script src="{deployUrl}/plugin/data-harbor/index.min.js"></script>
    <!-- 3. RRWebプラグインを読み込む：ユーザー操作を記録（オプション） -->
    <script src="{deployUrl}/plugin/rrweb/index.min.js"></script>

    <script>
      // 4. プラグインを登録、config情報は以下を参照：https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-data-harbor
      PageSpy.registerPlugin(new DataHarborPlugin(config));
      PageSpy.registerPlugin(new RRWebPlugin());

      // 5. PageSpyをインスタンス化
      window.$pageSpy = new PageSpy({
        // SDKとデバッグ側がリアルタイム接続を確立したくない場合は、オフラインモードを有効にできます
        // offline: true
      });
    </script>
  </head>
</html>
```

導入が成功すると、ページの右下にPageSpyのフローティングボールが表示されます。フローティングボールをクリックすると、ポップアップにアップロードとダウンロードのボタンが含まれます。

<a href={modalImg} target="_blank">
  <img src={modalImg} />
</a>

アップロードまたはダウンロードボタンをクリックすると、オフラインログデータが保存されます。

#### ステップ2：ログを再生#step-2

デバッグ側に入り、トップメニューの「デバッグを開始 - ログ再生」をクリックして再生リストページに入り、前のステップでアップロード/ダウンロードしたjsonデータを選択すれば再生機能を使用できます！

<a href={replayImg} target="_blank">
  <img src={replayImg} />
</a>

#### プラグイン説明#plugins

- **DataHarborPlugin**：オフラインログデータを収集・保存し、アップロード/ダウンロード機能を提供
- **RRWebPlugin**（オプション）：[rrweb]({VITE_PLUGIN_RRWEB})を使用してDOMの更新とユーザー操作軌跡を記録します。デバッグ側の「ログ再生」パネルの左側でページの操作録画を確認できます

### O-Spyの使用#use-ospy

[O-Spy](/o-spy)のSDKはプラグアンドプレイで、デプロイが不要です。PageSpy / DataHarborPlugin / RRWebPluginがパッケージされており、オフライン状態でのPageSpyのベストプラクティス設定が組み込まれています。同時にカスタムテーマもサポートしており、非常に簡単に使用できます。

フレームワークに依存せず、プロジェクトへの導入方法を自由に選択できます。

import { ImportGuide } from '@/pages/OSpy/components/ImportGuide';

<ImportGuide />

正常に導入されると、右下に「問題フィードバック」というドラッグ可能なコンポーネントが表示されます。

#### カスタマイズテーマの例#customize-example

import { CustomizeExample } from '@/pages/OSpy/components/Customize';

<CustomizeExample />

### ミニプログラムでの使用#mp

ミニプログラム環境でもオフラインログ再生をサポートしています。手順は以下の通りです：

#### ステップ1：ミニプログラム専用プラグインのインストール#mp-step-1
```bash
yarn add @huolala-tech/page-spy-plugin-mp-data-harbor
```

#### ステップ2：プラグインの登録#mp-step-2
```ts
import PageSpy from '@huolala-tech/page-spy-wechat';
import DataHarborPlugin from '@huolala-tech/page-spy-plugin-mp-data-harbor';

// プラグインを登録、config情報は以下を参照：https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-mp-data-harbor
const $dataHarborPlugin = new DataHarborPlugin(config)
PageSpy.registerPlugin($dataHarborPlugin);

const $pageSpy = new PageSpy({
  // ...
})
```

#### ステップ3：オフラインログのアップロード#mp-step-3

オフラインログをアップロードするには2つの方法があります：

**方法1：コード呼び出し**

```ts
$dataHarborPlugin.upload().then(() => {
  console.log('アップロード成功');
})
```

**方法2：デバッグメニューを使用**

ミニプログラムDataHarborプラグインを登録すると、PageSpyのデバッグメニューに「オフラインログをアップロード」ボタンが表示されます。クリックするとアップロードできます：

<a href={mpDataHarborImg} target="_blank">
  <img style={{width: 375}} src={mpDataHarborImg} />
</a>

## 延伸阅读#read-more

### 仕組み#how-it-works

ログ再生は[DataHarborPlugin]({VITE_PLUGIN_DATA_HARBOR})プラグインに基づいて実装されています。このプラグインはPageSpy内部の[`"public-data"`イベント](./plugins#convention)を監視して、実行時に生成されるすべてのデータを自動的に収集します。

### プラットフォーム差異#platform-differences

ログ再生機能においてプラットフォームごとに以下の差異があります：

| 機能 | ブラウザ | ミニプログラム |
| --- | --- | --- |
| データアップロード | ✅ サポート | ✅ サポート |
| データダウンロード | ✅ サポート | ❌ 非サポート |
| UI録画（RRWebPlugin） | ✅ サポート | ❌ 非サポート |

### FAQ#faq

#### 1. ログの手動アップロード/ダウンロードはどのように行いますか？

詳細は[DataHarborPlugin APIドキュメント](./data-harbor#onOfflineLog)をご覧ください。

#### 2. オフラインログはどこに保存されますか？

DataHarborPluginがデータを受信した後の処理フロー：

1. データはまずメモリ配列に格納される
2. メモリ内のデータが臨界値（デフォルト10MB）に達すると、自動的に一時ファイルに書き込まれる
3. ユーザーはいつでもデータをサーバーにアップロードしたり、ローカルに保存してダウンロードできる

メモリの臨界値をカスタマイズできます：

```ts
new DataHarborPlugin({
  maximum: 1 * 1024 * 1024, // メモリ内のデータが1MBに達したら一時ファイルに書き込む
})
```

#### 3. オフラインログはアプリケーションのパフォーマンスに影響しますか？

DataHarborPluginはパフォーマンス最適化されています：

- 非同期処理を使用し、メインスレッドをブロックしません
- メモリ使用を自動的に制御し、メモリオーバーフローを防止します
- データを圧縮して保存し、スペース使用量を削減します
